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Chrome DevTools is a webapp. 
It's JavaScript and CSS. It's open source. And it's hackable. That's what this doc is about. 
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Hello World 


e Open DevTools to the Elements Panel 


e Undock it via the menu in the top-left: C%*si#® O W O 


e Make sure Elements panel is visible 
e Use the keyboard shortcut to Open devtools (ctrl+shift+i or cmd-opt-i). You're now inspecting the 
inspector. 


Developer Tools - https://docs.google.com/document/d/1WNF-KqRSzPLUUfZqQGS5AFeU_LI8TfWYcJasa_XGf7ro/edit?ts=5a78clad = @ © © Developer Tools - chrome-devtools://devtools/bundied/inspector.htmI?remoteBase=https://chrome-devtools-frontend.appspot.com/serve file/@5e944b2d79bce5f96de35a05a... 


Or a Elements Network Performance Console Sources Application Memory Security » @8A1 oe Elements Network Performance Console Sources Application Memory Security Audits » 
eg alWayS=parent expanaea™ aria-expanaeo= 
"true" draggable="true">..</Li> Styles Computed Event Listeners >» 
¥<ol class="children expanded" role= 
"group"> Filter :hov .cls p 
»<li role="treeitem" class="parent" 
aria-expanded="false" draggable= 
"true">.</li> 
<ol class="children" role="group"> |, elements- elements/elemen..Outline. css:23 

















Styles Computed Event Listeners » 


element. style { 
»<iframe tabindex="-1" aria-hidden="true" style="position: } 
absolute; width: 9 eight: 9em; top: -99em;">..</iframe> body { 
><iframe tabindex: : aria-niddens: true" styl siti display: block; </ol> disclosure 
absolute; width: 9em; height: 9em; top: -99em;"'>..</iframe> lace anes Ae eo Li. parent { 
><span id="kix-wrapped-iframe" style="position: absolute; top: margin: > apx; selected expanded" aria-expanded margin-left: -13px; 
-50000px; white-space:nowrap; overflow: hidden">..</span> } true" draggable="true” tabindex="0 . 
»<script type="text/javascript" nonce>..</script> :ibefore 
»<noscript>..</noscript> <div class="selection fill" li.selected { elements/elemen..utline.css:334 
<meta itemprop="name" content="Chrome DevTools Contribution Ea hale NT z-index: 0; 
Guide"> <div class="gutter-container" 
<meta itemprop="faviconUrl" content="https://ssl.gstatic.com/ style="left: =1px; "></div> 
docs/documents/images/kix-favicon6. ico"> ><span class="highlight">..</span> 
<meta itemprop="url" content="https://docs.google.com/a/ ><span class="selected-hint">.. 
google. com/document/d/1WNF— </span> 





element.style { 
} 







user agent stylesheet 
























«elements— elements/elemen..0ut Line.css:13 
disclosure li 


padding: > @ @ @ 14px; 





KqRSzPLUUfZqQG5AFeU_LL8T fWYcJasa_XGf7ro/edit? </li> bordiho tox 
disco=AAAABpbYQPQ&ts=5a78clad&usp=comment_email_document&usp=e ¥<ol class="children expanded" role= 91 pe px; R 
mbed_googleplus"> "group"> 
<meta itemprop="embedURL" content="https://docs.google.com/a/ <li role="treeitem" class= word-wrap: break-word; 
google. com/document/d/1WNF- "parent" aria-expanded="false" position: relative; 
KgRSzPLUUfZqQG5AFeU_L18T fWYcJasa_XGf7ro/preview? draggable="true">..</li> min-height: 14px; 
usp=embed_googleplus"> <ol class="children" role= } 

><div "docs-chrome" tabindex="0" role="group">..</div> 





*{ ui/inspectorCommon.css:45 
box-sizing: border-box; 


"group"></ol> 

<div id="docs-texteventtargetbrailleoffsetcalculator"></div> <li role="treeitem" class= 
><div id="docs-aria-speakable" class="docs-ally- a 5 -expanded=""false" 
ariascreenreader-speakable docs-offscreen" aria-live="assertive" > 
Tmi Amc cc a i ui/inspectorCommon.css:7 











x { 





This is sometimes called “Inspector Inception”. 


See more at The Hello World of Chrome DevTools Hacking 


How to Hack on DevTools 


The supported workflows are documented in docs/workflows.md 


Testing 
This section moved to the testing document. 


Hack 


Hack on DevTools Frontend 
Make any change you like in the frontend. 


Refreshing is a little tricky when hacking on devtools. If your focus is within the DevTools, then Ctrl-R will 
reload the page it's inspecting. So, that'd be fine if you Ctrl-R in your DevTools-on-DevTools window. 
Protip: Alt-R (option + R on macOS) will reload the DevTools instance you're focused on. 


Caching: As this is a fresh DevTools profile, the "Disable Cache" checkbox is off. You'll want to turn that on, 
pronto. 


Inspector.html Query Params 

There are a few query parameters worth explaining: 

http: //localhost: 8090/front_end/inspector.html?can_dock=true&dockSide=right&ws=localhost: 
9222/devtools/page/1FFDE891 -34F1-485C-A@CB-@66EBF852E53 


e The can_dock=true&dockSide=right can help you emulate dock-to-right 


e Thews=... query parameter defines the websocket connection. 


Hacking FAQ 
1. Why aren't changes shown in the sources tab when | edit the DevTools source? 
a. The DevTools source files might be cached. Try checking the setting “Disable cache (while 
DevTools is open)” in DevTools settings. 
2. What about refreshing and making changes quickly? 
a. For productive development, you should use ‘-custom-devtools-frontend’ as listed in the 
workflows file. 
3. Can I make a pull request? 
a. Well, we don't have pull requests, but we can do something similar. Read about it in the 
Contribution Process 
4. How do I change branches in git, pull changes from master, etc? 
a. The depot_tools tutorial is infinitely useful here. 
5. Ihave more questions, and | can't find a good answer... 


a. Ping the chrome devtools mailing list: groups.google.com...google-chrome-developer-tools 
6. I can't see my local changes in DevTools. Why? 


a. You need to reload DevTools via alt+R (option+R on macOS) 

b. If "Opening in existing browser session" is printed after you run the command to launch Chrome 
with the --custom-devtools-frontend argument, close the browser session in question and re-run 
the command. 

c. (Make sure you've rebuilt the codebase after applying your changes) 


Understanding the Codebase 


Make full use of chromium codesearch. cs.chromium.org is invaluable. 
e Add ‘f:front_end’ to a search to scope it to the devtools frontend 
e Add `-f:out to exclude the minified devtools JS. Add °-f:test to ignore various test files. 


How DevTools Works 


DevTools is a web app that talks the DevTools Protocol over a WebSocket to a backend within Blink's C++. 
The devtools-frontend github wiki is the best current documentation on the various components of DevTools, 
including architecture, testing, etc 


Protocol & Backend connection 


Read this fantastic doc: Contributing to Chrome DevTools Protocol. 
Browse the homepage of the Chrome DevTools Protocol Viewer, especially ‘Listening to the protocol’ 


Target, Models, and Agents 
+ model: 
+ agent: backend dafrontend data object that syncs with the backendta object that syncs with the 
frontend. 
+ E.g. the ‘target.runtimeAgent()° is stubbed out by codegen (InspectorBackendCommands.js). 
The InspectorBackend class handles the connection. 
+ target: manages communication between the model and agents 


How Chromium works 


e Chrome University 2018 - YouTube 
e How Blink Works 


Compiling Chrome 


Of course, you'll need the full checkout of Chromium. 


There are a few gn build args we recommend: gist.github.com/paulirish/2d84a6db1b41b4020685 


Contribution Process 


Writing Your Patch 
The patch process helps keeping the project running smoothly. This way all efforts are coordinated and as little 
effort as possible is spent in patches that won't be accepted. 


e We need to a ticket filed on crbug.com to keep track of the work. Find an existing or file a new one. 

e If you can, comment on the ticket that you'd like to work on it, in case the team has a good reason why it 
hasn't been done yet. 

e Do your development 

e Don't worry about creating lots of small commits or writing lengthy commit messages, nobody will see 
your individual commits. All of your commits for a single patch will land as a single commit in the repo. 
When you're uploading your patch, you'll have a chance to write the patch description (similar to a Pull 
Request description). 

e If you create a new file, add a license notice at the top of the file: 


// Copyright 2020 The Chromium Authors. All rights reserved. 
// Use of this source code is governed by a BSD-style license that can be 
// found in the LICENSE file. 


Preparing Your Patch 
If your patch is finished, we have a few helpful tools to make sure your patch looks good. 
As part of the presubmit check, we will automatically run these. You can also run specific presubmit checks by 
using our “npm” commands: 
e ESLint for style rules - npm run check-lint 
e Closure compiler for type-checking -npm run check-type-closure 
To run these presubmit checks without uploading, you can run git cl presubmit --upload. 


Note: View the Code Style Appendix for details on specific style rules and which ES6 features we currently use. 


If you are an external contributor, and it’s your first patch, you'll need to create an account on 
chromium-review.googlesource.com and make sure to add yourself to the AUTHORS file. (example). 


Submitting Your Patch For Review 
Once you're done preparing your patch, it’s time to upload your changes. 


Protip: If you need extra guidance here, try these resources: 


o Install depot tools 
depot_tools_tutorial 


O 
o meowni.ca/chromium-101/#send-your-code-for-review 
o developer.chrome.com/devtools/contributing-legacy#step-6-upload-your-patch 


After that, you are ready to start the patch upload: 


# upload your patch to codereview... 


git cl upload 





Gotcha: If you see “git: 'cl' is not a git command”, then you need to add depot_tools repo to your PATH. Best to 
set it in your . bashrc or equivalent rc file. 

Gotcha: When running ‘git cl upload’, if python gives ‘ImportError: No module named checkdeps’, run 
‘git cl upload --bypass-hooks’. 


Your editor prompts you to write the patch description. 


Tips on writing a good patch description: 
e CL for DevTools can go to two different repositories: 
o If you are working on backend changes on chromium prefix your changelist (CL) title with 
“[DevTools]” 
m E.g:‘[DevTools] Fix DOM breakpoints sidebar pane exception’ 
o For changelists (CLs) in devtools-frontend do not add the “[DevTools]” prefix 
m E.g: ‘Fix DOM breakpoints sidebar pane exception’ 
Explain the change in as much detail as you like. 
When your patch is committed, the first line of the CL is used as the git commit title and the rest is used 
as the full git description. 
e Try to keep your CL title and description to 80 characters per line. 


Save and exit the editor to finalize the patch submission. 


Afterwards, you'll get the code review URL e.g. 
> remote: New Changes: 
> remote: https: //chromium-review. googlesource.com/#/c/chromium/src/+/90292 Fixes [WIP] 


At this point, your patch is on the code review server, but it hasn't been sent to any reviewers yet. You can 
upload WIP (work-in-progress) patches here as you develop. (Just like putting a branch on your github repo, but 
not submitting a PR yet). 


Adding Reviewers For Your Patch 
Once you're ready to add a reviewer, visit that URL, confirm your patch looks how you expect, and hit “Start 


Review” on the top. 

Don't know who should review your change? Click the [FIND OWNERS] button on the top right. You need a 
review from the owners of the file. Not sure who to pick? We recommend Jan to start: 
janscheffler@chromium. org 

In the message field, you can add "PTAL' (please take a look) or whatever other message you want. Protip: You 
can find all commonly used abbreviations here. 


Now, if you're ready for it to be reviewed, click the “Start Review” button: 


Reviewers (@ Pavel Feldman X Add reviewer.. 


cc © chromium-reviews@chromium.org X $ devtools-reviews@chromium.org X% 


apavlov+blink@chromium.org X% blink-reviews@chromium.org X% caseq+blink@chromium.org X 
kozyatinskiy+blink@chromium.org % lushnikov+blink@chromium.org X 
pfeldman+blink@chromium.org % 

Add CC.. 


Add a note for your reviewers... 


~| Preview formatting 


Code-Review No score 


Commit-Queue +2 | Not ready 
Mark as ready for review and send reply 


SAVE CANCEL START REVIEW 





You will be notified by email about any new messages from the reviewers. 


Updating Your Patch in the Review Process 


If reviewers will ask you to change something in your code, follow these steps: 
1. Make sure you are on your branch. 
Optionally, pull latest changes and rebase them with: git pull --rebase origin master 
Commit locally to your branch. 
Use our Closure Compiler to type-check your changes: npm run check-type 
Use eslint to lint your code (e.g. style, coding conventions): npm run lint 
Finally, upload everything to the server again: git cl upload 


anak WN 


7. Once complete, add a comment similar to "comments addressed, please take a look". Without a 
comment, reviewers will not know about your new patchset. 
Protip: Make sure you click “Reply” every time you've added a new set of inline comments, otherwise they are in 
draft mode and only you can see them. 


Broken layout tests 
Parts of the DevTools are tested using layout tests (aka web_tests). It may happen that your code will break 


them and you'll see an error message in the build logs. View the subtle "layout_test_results" link in order to see 
very readable results from these failures: 


e  json.output cache [logdog] 





124. webkit_tests (with patch) 
unexpected_fallures: 
virtual /pointerevent/ inspector /sources/debugger-breakpoints/dom- 
breakpoints.htmi 


Total executed: 40630 





( 26 mins, 42 secs ) 
ə  stdio cache [stdout] 


125. archive_webkit_tests_results (31 secs ) 


° to = stan 


ayout test results 
(zip) 







126. telemetry_gpu_unittests 


(with patch) on Ubuntu-12.04 ( 0 secs ) 


To run these tests locally in order to fix them,you'll need to compile Chromium first. After that, you can follow 
this guide to learn how to run the tests. Running all of them takes a lot of time, but you can run groups of tests 
or even individual tests by passing path to a directory, or a file, to the test runner: npm test 
inspector/extensions 


LGTM 


Once the review is given a “Igtm” (Looks good to me) by a reviewer, you can add it to the commit queue. To add 
to the commit queue, click the Submit to CQ button. This will start a final run of tests and land it after a green 
run. 





SUBMIT TO CQ - 


——| 





\o/ 


Patch FAQ 


e What do | do if my CL failed unrelated tests in the commit queue? 
o If the test failures look unrelated to DevTools (i.e. inspector tests), then try re-submitting it to the 
commit queue. 
e ‘git cl’ it saying there's no owner selected. 
o Ignore it, you'll be selecting a reviewer in the web UI. 
e Tests? 
o You may be asked by a reviewer to write a test. If so, read Web Tests 
e How do! update an existing CL with a new version of the patch? 
o When pushing an update, the system automatically remembers which remote issue is attached 
to your local branch. So nice. 


e How do I associate my local branches to codereview URLs? 
o “git map-branches* will show your active branches and their status 
o “git cl issue’ will reveal the issue URL for the current branch. 
o “git cl web’ will open that URL in your browser. 
e How do the devtools bugs in crbug.com work? 
o Guide to devtools crbugs DevTools Bug Triage how they work, how to browse, how to subscribe 


Appendices 


Appendix C: Code Style & Annotations 

e The JS code style of the DevTools is basically the Blink Coding Style Guidelines, which are for C++, but 

we'll apply them to JS. (Yup) 
o Aneslint configuration to check the basics is in the ‘devtools’ folder. Run with npm run lint. 
(This uses the locally installed eslint node module to ensure everyone is using the same version) 

e ES6 &DevTools: Read DevTools Style Guide for what's allowed/disallowed 

e DevTools frontend uses closure compiler with annotations for type-checking among other useful 
compile-time feedback. The compiler will run on presubmit, but you can run it on demand: 


npm run check-type-closure 


> 


Java executable: /usr/bin/java 


Checking duplicate files across modules... 
Compiling frontend... 

Compiling InjectedScriptSource. js... 
Compiling devtools. j 





Appendix D. Pointing your DevTools Instance at a Node Debug Session 


Start your node.js application (using node 6.3 or later) with the --inspect flag to allow the chrome devtools to 
be attached: 


$ node --inspect my-script.js 
Debugger listening on port 9229. 
Warning: This is an experimental feature and could change at any time. 


To start debugging, open the following URL in Chrome: 


chrome-devtools://devtools/remote/serve_file/@521e5b7e2b7cc66b4006a8a54cb9c4e57494a5eF/inspect 
or. html?experiments=true&v8only=true&ws=localhost :9229/node 





Note the highlighted query parameters above. With your instance of the devtools server running and canary 
running, append these parameters to chrome-devtools: //devtools/custom/inspector.html and load this 
URL in canary: 

chrome-devtools: //devtools/custom/inspector. htm] ERNARI ET ETE 


You should now be able to set breakpoints etc. against your running Node.js application. 











Appendix E: Keep an eye on the latest and greatest of DevTools development 


There's a few options here: 


e Follow these twitter accounts: @ChromeDevTools, @DevToolsCommits, @umaar, @malyw, @kdzwinel, 
@addyosmani, @paul_irish, @samccone, @mathias, @mattzeunert, @PrashantPalikhe, @ziyunfei, 
@bmeurer 

Subscribe to devtools-reviews@chromium.org mailing list for all reviews of pending code 

View all open DevTools tickets. 

Watch https://developers.google.com/web/updates/ for "What's new in DevTools" posts. 

Follow Umar's Dev Tips: https://umaar.com/dev-tips/ 


Use Chrome Canary and poke around the experiments. 


Appendix F: Outdated Resources 


These haven't been updated in a long time so they're probably irrelevant now. But they were cool. 
e Chrome DevTools Hacking Guides | Jason Laster 
o How does DevTools show the functions popup? 
o Diving into the source frames 
o Showing the Source Object Helper 
o What happens when DevTools Pauses 
e The life of a network header, from network stack to devtools 
e How the console evaluates by Zirak 
e blink class hierarchy diagrams 





